docs: Add a section on accessible buttons

Anything that behaves like a button should do so at the accessibility
level as well.

diff --git a/docs/reference/gtk/section-accessibility.md b/docs/reference/gtk/section-accessibility.md
index c86eb3c3c19a13c3c157ec9d6c35f84dadf81ef6..efafadd512d80b46c14b17e7e1b14e022cc86274 100644 (file)
--- a/docs/reference/gtk/section-accessibility.md
+++ b/docs/reference/gtk/section-accessibility.md
@@ -298,6 +298,16 @@ When creating custom widgets, following established patterns can help
 ensuring that the widgets work well for users of accessible technologies
 as well.
 
+### Buttons
+
+A button is a widget that enables users to trigger an action. While it is
+recommended you use #GtkButton for anything that looks and behaves like a
+button, it is possible to apply a button behavior to UI elements like images
+by using a #GtkGestureClick gesture. When doing so, you should:
+
+  - Give your widget the role %GTK_ACCESSIBLE_ROLE_BUTTON
+  - Install an action with no parameters, which will activate the widget
+
 ### Custom entries
 
 For custom entries, it is highly recommended that you implement the